From 08e443e0db6f74ade5836f8028073aeac14aab38 Mon Sep 17 00:00:00 2001 From: Emmanuele Bassi Date: Sat, 17 Sep 2016 12:47:39 +0100 Subject: [PATCH] docs: Update gtk_window_get_size() The main corpus of the documentation for gtk_window_get_size() is still full of X11-isms, so we should port it to something that is more backend-agnostic. Additionally, having some examples would be nice for application authors looking at a way to appropriately use this function. --- gtk/gtkwindow.c | 133 +++++++++++++++++++++++++++--------------------- 1 file changed, 76 insertions(+), 57 deletions(-) diff --git a/gtk/gtkwindow.c b/gtk/gtkwindow.c index d8b3c21a52..fc1e050f77 100644 --- a/gtk/gtkwindow.c +++ b/gtk/gtkwindow.c @@ -5400,63 +5400,82 @@ gtk_window_resize_to_geometry (GtkWindow *window, /** * gtk_window_get_size: * @window: a #GtkWindow - * @width: (out) (allow-none): return location for width, or %NULL - * @height: (out) (allow-none): return location for height, or %NULL - * - * Obtains the current size of @window. If @window is not onscreen, - * it returns the size GTK+ will suggest to the - * [window manager][gtk-X11-arch] - * for the initial window - * size (but this is not reliably the same as the size the window - * manager will actually select). The size obtained by - * gtk_window_get_size() is the last size received in a - * #GdkEventConfigure, that is, GTK+ uses its locally-stored size, - * rather than querying the X server for the size. As a result, if you - * call gtk_window_resize() then immediately call - * gtk_window_get_size(), the size won’t have taken effect yet. After - * the window manager processes the resize request, GTK+ receives - * notification that the size has changed via a configure event, and - * the size of the window gets updated. - * - * Note 1: Nearly any use of this function creates a race condition, - * because the size of the window may change between the time that you - * get the size and the time that you perform some action assuming - * that size is the current size. To avoid race conditions, connect to - * “configure-event” on the window and adjust your size-dependent - * state to match the size delivered in the #GdkEventConfigure. - * - * Note 2: The returned size does not include the - * size of the window manager decorations (aka the window frame or - * border). Those are not drawn by GTK+ and GTK+ has no reliable - * method of determining their size. - * - * Note 3: If you are getting a window size in order to position - * the window onscreen, there may be a better way. The preferred - * way is to simply set the window’s semantic type with - * gtk_window_set_type_hint(), which allows the window manager to - * e.g. center dialogs. Also, if you set the transient parent of - * dialogs with gtk_window_set_transient_for() window managers - * will often center the dialog over its parent window. It's - * much preferred to let the window manager handle these - * things rather than doing it yourself, because all apps will - * behave consistently and according to user prefs if the window - * manager handles it. Also, the window manager can take the size - * of the window decorations/border into account, while your - * application cannot. - * - * Note 4: When using client side decorations, GTK+ will do its best to - * adjust the returned values to match the logical size of the window - * excluding the widgets added for client side decorations, but there - * is no garantee that the result will be totally accurate because - * these widgets depend on the theme and may not be realized or - * visible at the time gtk_window_get_size() is invoked. - * - * In any case, if you insist on application-specified window - * positioning, there’s still a better way than - * doing it yourself - gtk_window_set_position() will frequently - * handle the details for you. - * - **/ + * @width: (out) (nullable): return location for width, or %NULL + * @height: (out) (nullable): return location for height, or %NULL + * + * Obtains the current size of @window. + * + * If @window is not visible on screen, this function return the size GTK+ + * will suggest to the [window manager][gtk-X11-arch] for the initial window + * size (but this is not reliably the same as the size the window manager + * will actually select). See: gtk_window_set_default_size(). + * + * Depending on the windowing system and the window manager constraints, + * the size returned by this function may not match the size set using + * gtk_window_resize(); additionally, since gtk_window_resize() may be + * implemented as an asynchronous operation, GTK+ cannot guarantee in any + * way that this code: + * + * |[ + * // width and height are set elsewhere + * gtk_window_resize (window, width, height); + * + * int new_width, new_height; + * gtk_window_get_size (window, &new_width, &new_height); + * ]| + * + * will result in `new_width` and `new_height` matching `width` and + * `height`, respectively. + * + * This function will return the logical size of the #GtkWindow, + * excluding the widgets used in client side decorations; there is, + * however, no guarantee that the result will be completely accurate + * because client side decoration may include widgets that depend on + * the user preferences and that may not be visibile at the time you + * call this function. + * + * The dimensions returned by this function are suitable for being + * stored across sessions; use gtk_window_set_default_size() to + * restore them when before showing the window. + * + * To avoid potential race conditions, you should only call this + * function in response to a size change notification, for instance + * inside a handler for the #GtkWidget::size-allocate signal, or + * inside a handler for the #GtkWidget::configure-event signal: + * + * |[ + * static void + * on_size_allocate (GtkWidget *widget, GtkAllocation *allocation) + * { + * int new_width, new_height; + * + * gtk_window_get_size (GTK_WINDOW (widget), &new_width, &new_height); + * + * ... + * } + * ]| + * + * Note that, if you connect to the #GtkWidget::size-allocate signal, + * you should not use the dimensions of the #GtkAllocation passed to + * the signal handler, as the allocation may contain client side + * decorations added by GTK+, depending on the windowing system in + * use. + * + * If you are getting a window size in order to position the window + * on the screen, you should, instead, simply set the window’s semantic + * type with gtk_window_set_type_hint(), which allows the window manager + * to e.g. center dialogs. Also, if you set the transient parent of + * dialogs with gtk_window_set_transient_for() window managers will + * often center the dialog over its parent window. It's much preferred + * to let the window manager handle these cases rather than doing it + * yourself, because all apps will behave consistently and according to + * user or system preferences, if the window manager handles it. Also, + * the window manager can take into account the size of the window + * decorations and border that it may add, and of which GTK+ has no + * knowledge. Additionally, positioning windows in global screen coordinates + * may not be allowed by the windowing system. For more information, + * see: gtk_window_set_position(). + */ void gtk_window_get_size (GtkWindow *window, gint *width, -- 2.30.2